Identifiers
An Identifier is a named value that can be defined and subsequently referred to during XML processing. In programming terms it is analogous to a variable.
Identifiers can significantly speed up XML processing if used intelligently. In particular, since scanning text from the PDF file is a fairly slow process, if your XML script frequently scans the same area of the Letter, then processing speed can be improved by creating an Identifier with the scanned text and then referring to it, rather than scanning the text again.
Whenever you see text in an XML schema that is enclosed in curly braces, it means that you have the option:
EITHER you can specify text directly (no curly braces)
OR you can specifiy an Identifier name (in curly braces)
Schema
<setIdentifier name="identifier-name"
[property="pdf-metadata-name"]
[field="custom-data-field-name"]
[letterValue="letter-record-column-name"]
[identifier="other-identifier-name"]
[scan="X,Y,W,H" [multiPage="start-end" [insertNewLine="true|false"] ] ] >default-text | {other-identifier-name}
<extendIdentifier [scan="X,Y,W,H"]
[identifier="different-identifier-name"]
[extendSeparator="text"] >default-text | {other-identifier-name}
</extendIdentifier>
</setIdentifier>
Creating Identifiers
N.B. "identifier-name" is the name of the Identifier you are creating, The value of the identifier is whatever text was scanned from the page, or obtained from one of the other sources. Identifier names are not case-sensitive.
The name attribute is mandatory. All other attribute are optional and specify the source from which the identifier value will be taken. Normally only one other attribute would be specified.
<setIdentifier name="identifier-name" property="pdf-metadata-name" />
The property attribute sets the identifier value to the value of the named PDF metadata property e.g. Title, Author, etc. Depending on the processing chain, HybridMail may add metadata properties called MkzFilename, MkzAddress, MkzZone, MkzSSC and these can also be used.
<setIdentifier name="identifier-name" field="custom-data-field-number" />
The field attribute sets the identifier value to the value of custom data field specified i.e. 1 to 10.
<setIdentifier name="identifier-name" letterValue="column-name" />
The letterValue attribute sets the identifier value to the value of the named column in the database record. Allowed column names are: "recipient", "address", "postcode", "name", "ssc", "dps" , "id", "date", "submitcode", "pages", "output", "template", "user", "status", "stream", "file".
<setIdentifier name="identifier-name" identifier="other-identifier-name" />
<setIdentifier name="identifier-name" >{other-identifier-name}</setIdentifier>
The identifier attribute or the presence of curly braces sets this identifier value to the value of the other identifier.
All the usual post-processing attributes can be used here.
<setIdentifier name="identifier-name" scan="X,Y,W,H" />
The scan attribute sets the identifier value to the text scanned from the letter.
All the usual post-processing attributes can be used here.
- Once the identifier has been created it can be used in place of any instance of the
scan attribute (including in a <setIdentifier> tag)
- An Identifier exists from the point it is created until all letter XML processing for the current phase is finished, even across different attachment elements and scripts. I.e. an identifier can be created in one XML file and referenced in another XML file.
- Identifiers only exist for the duration of the current processing phase. I.e. an identifier created during the onSubmit phase cannot be referenced during the onRelease phase; it will have to be recreated.
- A reference to a non-existent identifier is always ignored and substituted with an empty string.
- If you create an identifier with the same name as a previously created one, the new identifier replaces the old one.
Extending Identifiers
An identifier can be extended, conditionally if required, by using the following XML syntax:
E.g. Create an identifier named "fred" with a value that is a concatenation of the text in regions "20,20,20,20" and "55,55,55,55", separated by a new-line character "\n".
<setIdentifier name="fred" scan="20,20,20,20" >
<extendIdentifier scan="55,55,55,55" extendSeparator="\n" />
</setIdentifier>
The default value of the extendSeparator attribute is a single space.
E.g. Create an identifier named "fred" with a value that is the text in region "20,20,20,20" plus the text in either region "55,55,55,55" on page 2 or "66,66,66,66" on page 3, depending on whether the region "11,11,11,11", contains the word "harry" or not.
<setIdentifier name="fred" scan="20,20,20,20" >
<extendIdentifier scan="55,55,55,55" page="2" >
<condition scan="11,11,11,11" contains="harry" />
</extendIdentifier>
<extendIdentifier scan="66,66,66,66" page="3" />
<condition scan="11,11,11,11" notContains="harry" />
</extendIdentifier>
</setIdentifier>
An identifier can also be created from text scanned from a set of pages
E.g. Create an identifier named "fred" with a value that is a concatenation of the text in region "20,20,20,20" on pages 1, 2 and 3
<setIdentifier name="fred" scan="20,20,20,20" multiPage="1-3" />
When an Identifier is created using the multiPage attribute, any extensions are scanned from the 'current' page before the next page is considered.
E.g. create an identifier named "fred" whose value is:
The text scanned from "20,20,20,20" on page 1, plus
The text scanned from "55,55,55,55" on page 1, plus
The text scanned from "20,20,20,20" on page 2, plus
The text scanned from "55,55,55,55" on page 2.
<setIdentifier name="fred" scan="20,20,20,20" multiPage="1-2" >
<extendIdentifier scan="55,55,55,55" />
</setIdentifier>
When the multiPage attribute is used, the insertNewLine="true" attribute can optionally be added. This causes a new line character "\n" to be inserted in between each scanned page.
<setIdentifier name="fred" scan="20,20,20,20" multiPage="1-2" insertNewLine="true" />
The default value of the insertNewLine attribute is a single space.